Skip to content

Show more of the parser in the README example - #340

Merged
derek73 merged 2 commits into
masterfrom
docs/readme-usage-example
Aug 7, 2026
Merged

Show more of the parser in the README example#340
derek73 merged 2 commits into
masterfrom
docs/readme-usage-example

Conversation

@derek73

@derek73 derek73 commented Aug 7, 2026

Copy link
Copy Markdown
Owner

Summary

The 1.4 README showed the whole parse at once through the repr. 2.x had shrunk to two attribute accesses on one Western name, which showcases very little of what the parser now does.

This brings the repr back and adds six scripts.

What it shows now

  • The repr, the only thing that shows every field in one place
  • family_base / family_particles, a 2.x view 1.4 had no equivalent for, which makes the particle handling visible
  • Six scripts, all under the default configuration: Chinese and Japanese family-first, the Korean census split, a glued honorific, a Cyrillic title, and the Arabic بن chain
  • One locale pack, last, because Russian patronymics are the one case here that does not work by default. Сидоров Иван Петрович parses wrong without locales.RU, so showing the pack is more honest than picking a Cyrillic example that happens to need nothing.

Choices worth reviewing

No subheadings, no explanatory prose. The comments carry it, per review feedback. Blank lines group the three ideas.

The Arabic line keeps its trailing comment like the others, for consistency. Renderers give code blocks an LTR base direction, so it reads correctly; I had considered moving its explanation to prose to avoid bidi mixing, but that would have meant a heading or a paragraph, which is what we were removing.

Dropped the "Those seven fields are…" paragraph. The intro two paragraphs above already names all seven, and the repr now shows six of them (maiden is omitted when empty, as it is here).

Verification

  • python -m doctest README.rst15 tests pass (was 4); this runs in CI
  • Valid RST — docutils.publish_doctree reports no warnings
  • twine check on the built sdist — PASSED, so PyPI will render it
  • uv run pytest -q — 3065 passed

No code changed.

🤖 Generated with Claude Code

The 1.4 example showed the whole parse at once through the repr; 2.x
had shrunk to two attribute accesses. The repr is back, since it is the
only thing that shows every field in one place, and family_base /
family_particles come with it because the particle split is a 2.x view
1.4 had no equivalent for.

Six scripts now, all under the default configuration: Chinese and
Japanese family-first, the Korean census split, a glued honorific,
a Cyrillic title, and the Arabic bn chain. Russian patronymics go last
because they are the one case here that needs its pack, which is worth
showing rather than hiding.

No subheadings and no explanatory prose. The comments carry it.

Dropped the paragraph naming the seven fields: the intro two
paragraphs up already names them, and the repr now shows them.

Every line is doctested by the README doctest CI step. Verified the
file is still valid RST and that twine accepts it as a long
description, since PyPI renders it.
@derek73 derek73 added this to the v2.1 milestone Aug 7, 2026
@derek73 derek73 added the docs Documentation fixes and updates label Aug 7, 2026
@codecov

codecov Bot commented Aug 7, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.48%. Comparing base (85dcc69) to head (aaf8836).

Additional details and impacted files
@@           Coverage Diff           @@
##           master     #340   +/-   ##
=======================================
  Coverage   98.48%   98.48%           
=======================================
  Files          41       41           
  Lines        2845     2845           
=======================================
  Hits         2802     2802           
  Misses         43       43           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

The example was '毛 泽东', spaced, which is not how Chinese names are
written. It was chosen because the spaced form demonstrates
family-first order without needing a pack, but that is a capability
shown against input nobody has: a reader who tries the realistic
'毛泽东' gets the whole name in family and concludes it does not work.

It now uses '毛泽东' under locales.ZH, which is both the real spelling
and the real answer, and it sits beside the Russian patronymic because
they need a pack for the same class of reason.

That grouping is the honest one. Korean unspaced works by default
because hangul is written by one language and its surnames are a
closed census set; Han text cannot say which language wrote it, so a
Chinese surname list would split 高橋一郎 in the wrong place. The
comment says so.
@derek73
derek73 merged commit 57d328c into master Aug 7, 2026
11 checks passed
@derek73
derek73 deleted the docs/readme-usage-example branch August 7, 2026 07:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation fixes and updates

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant